Implementing web embed interfaces

The web embed can be built with either:

1. the Create a case action, or
2. the Display a page action.

Option 1: Use the Create a case action (Recommended)

The Create a case action provides all the necessary case management features, including pre-processing, post-processing, and validation, which are all available in the case configuration. Additionally, data can be persisted across multiple data objects with transaction consistency.

Option 2: Use the Display page action

The display page actions are more suitable for displaying information. However, the data collected for vendors or business partners consists of multiple data objects, such as address and contact information. The default DX APIs only support data entry for top-level data objects. Furthermore, the landing page layout is in a tabular format by default, which displays multiple records, including registrations of other users, and this might pose a potential data security risk. Also, business partner registration requires approval from executive manager.

To create a case for web embed, you first download the MDCSample.zip file from the Rule-File-Binary as shown in the following figure:

Extract MDCSample.zip to a opt/tomcat/webapps directory, and then launch the Pega WebEmbed with <cite>http://<host>:<port>/PASample/</cite>. 

The HTML files in the unzipped MDCSample directory can be opened directly. The index.html file is opened first when accessed by a web server such as Tomcat. You can also click case1.html and case2.html directly.

You use the WebEmbed interface configuration view in Dev Studio or App Studio to generate the WebEmbed code in the case1.html and case2.html files. CASE 1 launches the Business Partner registration case. CASE 2 launches the Truck Vendor Registration case. The cases can be launched by clicking MENU in the upper-right corner of the workspace.

Savable data pages

Savable data pages are used to fetch, add, update, and delete information. The D_SavableBusinessPartnerWrapper data page is used to fetch existing partner details or save partner details into the database. Each Business Partner object consists of address and contact information as embedded objects. The D_SavableBusinessPartnerWrapper data page stores the top-level partner information, while the embedded "Address" and "Contact" objects are saved to D_AddressSavable and D_ContactSavable, respectively. Because the address is a list, D_AddressSavable is called for each page in the list. Updating partner information follows a similar approach, where pyGUID needs to be passed as a parameter for the record to be updated. The same data page, D_SavableBusinessPartnerWrapper, can also be used to delete an existing partner record by setting the pyActionType property.

Similarly, D_SaveFreightVendorWrapper is used to fetch and add truck vendor data to the database. D_FreightVendorSavable saves the top-level data, while information about the address and contact details are saved to D_AddressSavable and D_ContactSavable, respectively.

Web embed authentication

Authentication ensures that only users and systems with a verified identity can use the WebEmbed , and that all permitted manipulations of the data occur under the current user identity.

In earlier versions of Pega Platform for mashup, the Anonymous Authentication Service (AAS) was used to establish authentication. However, this is not supported in Constellation-based web embeds.

Configuring authentication for web embeds

For Web Embeds there are three types of Authentication mechanisms available:  

1. Authorization code 

When using the Authorization code grant flow, OAuth is utilized, and the Alias of a Custom Authentication Service must be specified. In this scenario, the OAuth authorization code grant flow still occurs, but custom activity governs which operator is eventually mapped to. The custom activity code needs to have logic to dynamically create external operators. (Note: When generating web embed channels, such custom authentication services do not appear on the drop-down menu). The custom authentication service rule should include an activity that takes inputs to the request, such as cookies, and maps them to a specific dynamic operator or rejects the request. The activity should interact with Pega OAuth 2.0 grant flow or interact with external identity access providers to authenticate the user. 

2. Custom bearer  

Uses OAuth and the new Custom Bearer public grant flow, which also uses custom activity logic to determine the operator (so that there are no redirects). 

3. None (Custom) 

Does not use an OAuth grant flow, but instead specifies the explicit authHeader to use (grantType="none"). 

Authentication of the WebEmbed is handled using OAuth2.0. For more information, see Authentication in web embed.

The steps for custom bearer configuration are as follows:

Step 1: Create the dynamic system settings (DSS)

Once the grant type is configured, create a DSS named CustomAuthForPegaEmbed in the Pega-Engine ruleset and enter True in the Value field. This enables custom bearer authentication for the web embed.

Step 2: Configure authentication on the Web embed

The Constellation web embed only supports OAuth 2.0. To configure authentication on the web embed, in App Studio, click Channels > Web Embed to configure a new web embed, or click Current Channel Interfaces to view existing web embeds.

When the web embed configuration opens, the Grant Type drop-down list is displayed. Because there is no identity provider system in place, we use the custom bearer option in the Grant Type.

After clicking Generate Web Embed Code, the code includes a ClientID field that is unique to each web embed.

Step 3: Update the Client to accept the Custom bearer

After saving the web embed configuration, an OAuth client registration is generated. Switch to Dev Studio and open the client registration for the web embed from the Records Explorer. When the client registration rule opens, under Supported Grant Type, ensure that the Custom Bearer checkbox is selected. 

Step 4: Update the client registration with utility to identify the operator

After selecting the Custom Bearer checkbox, an activity needs to be created to set the operator details. Based on the client ID, a specific operator must be mapped. The client ID can be mapped from the postBodyContent parameter. Once the client ID is parsed from the parameter, a decision table can be used to fetch the operator profile. The operator instance must be copied to the pyOperPage page, which is then passed as a parameter and processed by the authentication engine. See the pyPegaOAuthAccessTokenAuthenticationActivity activity for more information.

Step 5: Update the oAuth2.0 service package to point to the application-specific access group

By default, the OAuth Service package points to the Pega Platform application. The service access group must be updated to point to our application. Access to the application is controlled through the access group and the AROs.